home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 10 / AACD 10.iso / AACD / Resources / System / BoingBag1 / Contributions / Workbench / C / find.doc < prev   
Text File  |  1999-10-03  |  10KB  |  299 lines
  1. Short:     File Finder (custom search and output)
  2. Author:    soenke@vapor.com (Sönke Tesch)
  3. Uploader:  soenke@vapor.com
  4. Type:      util/dir
  5. Replaces:  util/dir/Find.lha
  6. Keywords:  Find Search File
  7. Interface: CLI Shell
  8.  
  9. What`s it all about?
  10. ====================
  11.  
  12. This is probably the 10315th implementation of a File Finder. Anyway,
  13. I spend a full 2½ hours on the first version, even got some mails and
  14. therefore I like it best and and wrote a smarter update :)
  15.  
  16. Find will search in a directory and its subdirectories for objects
  17. matching a given pattern. You can say where, where not and how deep
  18. Find should search and if it should return only files or directories
  19. or both.
  20. The output is customizable similar to c:lists` LFORMAT option.
  21.  
  22. Find does not need any extra libraries nor does it feature a text viewer,
  23. database or coffee-machine. Want a fancy MUI user interface with fifty-
  24. thousand buttons? Go and look for another program, Find is CLI-only ,)
  25.  
  26.  
  27. How to use
  28. ==========
  29.  
  30.   Find PATTERN/A,LOCATIONS=ROOTDIR/M,DEPTH/N/K,DIRS/S,FILES/S,HEADER=STATS/S,
  31.        QUIET/S,PRINTSEARCHED/S,PRINTSKIPPED/S,LFORMAT=FORMAT/K
  32.  
  33.   PATTERN
  34.     Name of the file or directory you are looking for. This string may
  35.     also contain standard AmigaDOS wildcards like #,?,~ etc. Please see
  36.     your AmigaDOS manual for further details.
  37.     Find doesn`t support paths here (e.g. txt/Hello) and will return
  38.     error code 210 (Invalid Component Name) in this case.
  39.  
  40.   LOCATIONS (former ROOTDIR)
  41.     Find usually starts searching in the current directory and its sub-
  42.     directories. To let you search in other places the argument ROOTDIR
  43.     was defined in version 1. This argument has been extended and renamed
  44.     to LOCATIONS for Find².
  45.  
  46.     You may now give any number (well, actually 255;) of directories to
  47.     search in. These names may also contain wildcards.
  48.  
  49.     Furthermore you can exclude directories from the search by using a
  50.     - or a ! as the first character. There`s a small difference between
  51.     the - and the !: ! will exclude _any_ directory that matches the
  52.     given name regardless where it`s located. Like PATTERN ! works with
  53.     path-less directory names only (i.e. with "blabla" but not with
  54.     "txt/blabla").
  55.  
  56.     NOTE:
  57.       To exclude a directory means to exclude all its subdirectories, too!
  58.       However, you may of course include a subdirectory of an excluded
  59.       directory.
  60.  
  61.     Take the following directory structure as an example:
  62.     ----------------------------------------------------------------------
  63.  
  64.     1> dir all ;; current directory is Find
  65.            txt (dir)
  66.                 test (dir)
  67.                   test2
  68.              Find.mod                         Find.mod_2.0
  69.              Test.mod
  70.            obj (dir)
  71.              Find.obj                         Test.obj
  72.            testdir1 (dir)
  73.                 testdir2 (dir)
  74.                   test1
  75.         cmc.opt                          Find
  76.         Find.lha                         find.mtx
  77.         find.readme                      test
  78.         test.mtx
  79.  
  80.     1> find test?
  81.     txt/test/test2
  82.     testdir1/testdir2/test1
  83.  
  84.     1> find test? test#? printsearched
  85.     Scanning testdir1
  86.     Scanning testdir1/testdir2
  87.     testdir1/testdir2/test1
  88.  
  89.     1> find #?st(?|%|.m[a-y]d)  ;; AmigaDOS wildcards are powerfull! :)
  90.     txt/test
  91.     txt/test/test2
  92.     txt/Test.mod
  93.     txt/testdir1/testdir2/test1
  94.     test
  95.  
  96.     1> find test? !test#? printsearched printskipped
  97.     Scanning txt
  98.     Skipped txt/test
  99.     Scanning obj
  100.     Skipped testdir1
  101.  
  102.     1> find test? -txt/test#? printskipped
  103.     Skipped txt/test
  104.     testdir1/testdir2/test1
  105.  
  106.     1> find test? -test#? printskipped
  107.     txt/test/test2
  108.     Skipped testdir1
  109.  
  110.     1> find test? !txt/test#? printskipped
  111.     txt/test/test2
  112.     testdir1/testdir2/test1
  113.     ;; didn`t work: ! doesn`t support paths
  114.  
  115.     ----------------------------------------------------------------------
  116.  
  117.     + is also supported as first character. This will do exactly the same
  118.     as if you omit it; it`s just there for completeness.
  119.  
  120.     NOTE:
  121.       · If you have a name that starts with +, - or ! you`ll have to
  122.         put one of +, - or ! in front of it in order to make it work
  123.         correctly!
  124.       · Use "-Mr Spacey:blabla" instead of -"Mr Spacey:blabla"!
  125.  
  126.   DEPTH
  127.     Maximum level of sub-directories Find will search in. The current
  128.     directory (or LOCATION if used) is level 0.
  129.  
  130.       find EggPaint dh0: depth 0
  131.  
  132.     will thus search only in the root of dh0:.
  133.     The default is unlimited.
  134.  
  135.     NOTE:
  136.       If Find finds a matching link it will return the path and filename
  137.       of the file the link points to, _not_ of the link! Therefore you
  138.       may get files very deep in your directory tree although you set
  139.       DEPTH to 1 or even 0. This is not my fault, it`s just the way
  140.       the NameFromLock() function in dos.library works.
  141.  
  142.   DIRS
  143.     Find returns only directories matching PATTERN.
  144.  
  145.   FILES
  146.     Find returns only files matching PATTERN.
  147.  
  148.   HEADER (former STATS)
  149.     Find will print some extra information after the search, e.g.
  150.  
  151.       1 files and 5 directories in 2 of 7 places (0 skipped)
  152.  
  153.     This obviously means Find found 1 matching file and 5 matching
  154.     directories in 2 directories. Find searched in a total of 7
  155.     directories and skipped 0.
  156.  
  157.   QUIET
  158.     By default Find prints some information about where it is currently
  159.     looking for matching objects to the Shell window. This output can be
  160.     switched off by setting QUIET.
  161.     QUIET doesn`t affect output of PRINTSEARCHED and PRINTSKIPPED, so
  162.     if both of these are set, QUIET is actually useless.
  163.  
  164.     Setting QUIET may speed-up the search significantly, simply due to
  165.     the fact that text output is a bit slow on some configurations.
  166.  
  167.   PRINTSEARCHED
  168.     Find prints a list of the directories it searched in.
  169.  
  170.   PRINTSKIPPED
  171.     Same as PRINTSEARCHED but will print a list of the directories it
  172.     skipped.
  173.  
  174.   LFORMAT or FORMAT
  175.     This is similar to the c:list argument LFORMAT. The given string is
  176.     written to the output for every matching object. The following commands
  177.     are supported:
  178.  
  179.       %s - inserts full path and name of the object
  180.       %n - inserts the name of the object
  181.       %p - inserts the _full_ path of the object. This is different to
  182.            c:lists` %p which prints the path relative to the current
  183.            directory.
  184.  
  185.     Example:
  186.  
  187.       Find EggPaint#? format "Found the magnificent %n in %p."
  188.  
  189.     might output
  190.  
  191.       Found the magnificent EggPaint in My First Disk:Gfx.
  192.  
  193.     NOTE:
  194.       Find² now automatically appends a carriage return to the end of
  195.       the string. This is different to version 1.
  196.  
  197.  
  198. Stop-That-Work® Option
  199. ======================
  200.  
  201.   Pressing ctrl-c will do a full stop, ctrl-e will stop the current
  202.   directory scan only.
  203.  
  204.  
  205. Return Codes
  206. ============
  207.  
  208.   Code  Level Meaning
  209.      0        No matching objects found.
  210.      5  warn  Object(s) found - number is in local variable Result2.
  211.               You can use c:get to read it.
  212.     10  error One or more LOCATIONs not found.
  213.     20  fail  Usually out-of-memory condition.
  214.     21    "   Arguments didn`t match.
  215.     22    "   Wildcards in PATTERN are not valid or a path was given.
  216.     23    "   Either wildcard problem or something went wrong while
  217.               searching for matching directories.
  218.     30    "   Virus Warning.
  219.  
  220.  
  221. Copyright
  222. =========
  223.  
  224.   Find, Find.readme and Find.doc:
  225.    Copyright 1997 by Sönke Tesch
  226.    All Rights Reserved.
  227.  
  228.   You may re-distribute the archive as long as no file is removed or
  229.   changed.
  230.   Find has to be distributed for FREE, any other kind of distribution
  231.   without my written permission is not allowed. However, this is not
  232.   the case for any AmiNet-CD. Others please feel free to ask.
  233.   I do not give any guarantee for the quality and usefulness of Find
  234.   nor that it works as described or fits particular needs.
  235.  
  236.  
  237. Contact
  238. =======
  239.  
  240.   Comments, suggestions, bug-reports and Hey-I-use-it!-mails are
  241.   always welcome! Just write to <soenke@vapor.com>.
  242.  
  243.  
  244. Those finer details..
  245. =====================
  246.  
  247.   Find features a simple build-in virus self-protection.
  248.  
  249.   Find is written using Cyclone Modula-2 by Marcel Timmermans.
  250.   The source is available on request, just ask.
  251.  
  252.   Find is still smaller than this document :)
  253.  
  254.  
  255. History
  256. =======
  257.  
  258.   03-Oct-99 2.04 + replaced * with ! (* may be used as #? replacement)
  259.                  + a few cosmetical optimizations (breaks and "Scanning..")
  260.  
  261.   06-Aug-97 2.03 ¤ bugfix in DoDir()
  262.                  + even more optimizations
  263.                  ¤ viruscheck wasn`t enabled (boo:)
  264.                  a released on Aminet
  265.  
  266.   21-Jul-97 2.02 ¤ Fixed bug in output routine (didn`t clear lines)
  267.                  + various optimizations to get size below the magic 5k
  268.                  + returns error if PATTERN is a path
  269.                  ¤ (hopefully) solved problem that ctrl-e didn`t work
  270.                    from time to time
  271.                  a released on Aminet
  272.  
  273.   10-Jul-97 2.01 + Total number of found objects returned in Result2
  274.                  + Fixed return codes so that they better match the
  275.                    system standards
  276.                  ¤ Although I wrote it wouldn`t QUIET did suppress
  277.                    output of PRINTSKIPPED and PRINTSEARCHED
  278.                  + Non-existing LOCATIONs return error code 10
  279.  
  280.   09-Jul-97 2.00 + added * to control search
  281.                  + FORMAT now supports %n and %p
  282.                  + PRINTSKIPPED & PRINTSEARCHED
  283.                  a non-public gamma release
  284.  
  285.   08-Jul-97 2.00 + search locations may be controlled by + and -
  286.  
  287.   19-May-97 1.00 a Version 1.00 on Aminet
  288.  
  289.  
  290. Have fun,
  291.   soenk.e
  292.  
  293.  
  294. --
  295. Amiga Translators Organization * Main & German Admin, Ex-Human Listserver
  296. ato    : ato-admin-de@ato.vapor.com & ato-admin@ato.vapor.com
  297. private: soenke@vapor.com
  298.  
  299.